fix(files): serve the Claude scratch fallback only from what was opened in its folder (#2259) - #2265

…ading (#2296) (#2297)

Closes #2296

## Problem

`server/file-pool.test.ts` hung CI's Fast checks on run
[40779586477](https://github.com/devswha/ovis/actions/runs/40779586477)
(#2293, which does not touch it): the job was cancelled at its 10-minute
limit with this file the only one never reported.

The test "keeps a descriptor its thread is reading open until that
thread is gone, when the last server stops" holds its file thread with
the fake worker's `readGate` (`server/file-worker.fake.ts`, from #2256).
That gate said the thread was reading (`Atomics.notify` on cell 1)
**before** it opened the FIFO for reading, a blocking `open(2)`. The
test then ends the thread (`release()`) and opened the FIFO's writer
with a blocking `openSync(fifo, "w")` on its main thread. A thread ended
between the notify and its own open never opens the reader, so the
writer's open waits forever, and Bun's per-test timeout cannot fire
while the main thread is blocked in a system call. #2265's PR body named
this gap as a candidate flake.

## Change (test-only)

- `readGate` opens the FIFO read-write (an open that never waits)
**before** it records the descriptor and notifies, then blocks in a
one-byte read of it, as `authorizeGate` (#2265) already does. Once the
test sees the thread running, the FIFO always has a reader, even after
that thread is ended.
- The test releases the read with `O_WRONLY | O_NONBLOCK` and a one-byte
write, which never waits (and would fail with `ENXIO` rather than hang
if there were no reader).
- Both FIFO gates (`readGate`, `authorizeGate`, now one `holdOnFifo`)
name their FIFO descriptor in a third gate cell, and the test closes it
once the thread is gone: a worker ended inside that read never runs its
`finally` on Bun, so before this each run left 2 FIFO descriptors open
(found from CodeRabbit's review; `/proc/self/fd` count at the end of the
file: 2 -> 0).

`server/file-pool.ts` is not changed: the server's thread never waits on
a file thread (it posts a task, ends a thread with `terminate()` without
awaiting it, and closes descriptors), so the product cannot block this
way. Only the tests await `fileThreadsClosed()`.

## Verification

- Widened window, scratch only (a 500 ms `Atomics.wait` right after the
notify in `readGate`):
- on main 72f2edf: `timeout 30 bun test server/file-pool.test.ts` is
killed at 30 s (exit 124), stopped in that test;
  - with this fix: exit 0 in 1 s, 12 pass.
- 50 runs of `bun test server/file-pool.test.ts`, 10 at a time pinned to
2 cores (`taskset -c 0,1`), each under `timeout 60`: 50 pass, 0 hangs.
Again pinned to one core (`taskset -c 0`): 50 pass, 0 hangs.
- Leaked FIFO descriptors at the end of the file (`/proc/self/fd`,
scratch probe): 2 before, 0 after; on 80b8cb2 the widened window again
passes in 1 s and 50/50 runs pinned to one core pass.
- `bun run check fast`: green on 80b8cb2 (typecheck, build, generated
files, workflow syntax; unit 8380 pass, 0 fail, 34 skip in 535 files).

## Review

omo-native-code-reviewer: PASS (APPROVE), no CRITICAL/HIGH/MEDIUM. It
found no path left that blocks the test's main thread (the remaining
waits are the non-blocking open and write, `hold.ran()`'s 10 s bounded
wait, and awaited promises), confirmed the release cannot hit
ENXIO/EAGAIN, and checked that a failing assertion while the thread is
parked fails fast instead of hanging. A second omo round on 80b8cb2
(the FIFO-descriptor take-back): PASS (APPROVE), reproduced 2 leaked
FIFO descriptors at 65a8a71 and none at 80b8cb2. No Codex review:
test-only, `server/file-pool.ts` unchanged.

## Known limits (LOW, not fixed here)

- If the thread is ended after its notify but before it enters the FIFO
read, the test still passes but does not exercise a read in flight in
that run (a false pass, never a hang). Every gate that notifies before
it blocks has this window, `authorizeGate` included.


The reviewer's findings and how each was resolved are in a PR comment.

…ollected (#2286) (#2317)

Closes #2286

## Problem

A Claude Code scratch file larger than one read (256 KiB) on a fast
Linux disk is sent as `Bun.file("/proc/self/fd/N").slice(...)` (#2265),
a file body Bun sizes itself. Its descriptor must outlive Bun's lazy
open, so a `FinalizationRegistry` closes it once both the body and its
answer are collected. Past 256 such bodies waiting for collection,
`fileResponse` streamed the body from its descriptor instead, and Bun
drops the Content-Length of any stream body. Many parallel downloads
reach that cap before a collection runs. Reproduced on main with 300 KiB
scratch files, 1,800 requests over 16 parallel connections from another
process: **73 to 98 of 1,800** answers came back chunked, with no size
or progress.

## Change

- **Cap:** raised from 256 to a quarter of this process's open-file
limit, at most 32,768 descriptor-named bodies.
- Only bodies actually being sent are really held, and those are bounded
by open connections. The rest are sent bodies waiting for a collection.
- Sent bodies that lived through a collection while they were sent wait
for one of Bun's own full collections, so the held count rises and falls
with those. The peaks, measured with no cap on a 1M-object heap, were
1,942 over 60,000 downloads 16 at a time and 6,657 over 30,000 downloads
64 at a time.
- The limit is read once from `/proc/self/limits`; only Linux takes this
path. Bun raises the soft limit to the hard one at start (a soft limit
of 1,024 became 524,288 here), so most hosts get 32,768.
- A host whose hard limit is 1,024 keeps main's 256, leaving the rest
for the server's own sockets, terminals and file threads. When the limit
cannot be read the cap is 256.
- **Collection requested, never forced:** past 256 held bodies (a
quarter of the cap when that is lower), a collection is requested on the
collector's own threads (`Bun.gc(false)`), at most once every 250 ms,
and no answer waits for it.
- That frees only bodies made since the last collection: about half the
peak in a burst, not ones that lived through a collection.
- There is never a forced collection (`Bun.gc(true)`), which holds every
terminal, key and request on the server's thread for as long as it takes
on the whole heap.
- Past the cap, a body is still streamed from its descriptor, as before.
- **Unchanged:** descriptor handling and #2259's confinement. A
descriptor is still closed only once both the body and its answer are
collected.

The first version of this PR forced a collection at the cap. The merge
pass measured it stopping the event loop for 215–300 ms per collection
on a ~300 MB heap during a seek burst, so it was replaced.

Alternatives measured on Bun 1.4.3 and rejected:
- **A sized `ReadableStream`:** Bun drops Content-Length for every
stream body.
- **`Bun.file(fd).slice()`:** Bun sends the whole file's size as
Content-Length with only the slice's bytes, a wrong header.
- **Closing the descriptor when the body is done:** there is no hook for
it, because `request.signal` does not abort after a sent or a cut
answer.
- **Requesting a collection early while keeping the 256 cap:** 88–97 of
1,800 were still chunked, because the collection lands too late.
- **The same, plus a non-blocking wait at the cap:** 52–64 of 1,800
chunked, about 2.5 times slower.

## Verification

- **Load test** (separate client process, the real file-thread pool, 300
KiB scratch files, 16 at a time):
  - main: 73–98 of 1,800 chunked in every run.
- This branch: 0 of 1,800 in every run, and 0 of 10,000 on a 1M-object
heap. Every body had the right bytes and length.
- **Sustained load** (64 at a time, 30,000 downloads, 1M-object heap): 0
of 30,000 chunked, where a 4,096 ceiling lost 3,166 to 8,086 and main
lost 28,976.
- **Seek burst** (1M-object heap, 256 bodies truly held, 512 range
requests 16 at a time, the server's event-loop lag sampled every 2 ms),
three alternating rounds:

| Tree | Stalls over 50 ms per burst | Answers without a length | Burst
time |
|---|---|---|---|
| main | 1 (99–191 ms) | 512 of 512 | 254–373 ms |
| first version (0f2a44a) | 9 (786–860 ms in total) | 512 of 512 |
844–1,161 ms |
| this branch | 1 (132–184 ms, the heap's own collection, as on main) |
0 of 512 | 265–478 ms |

- **New tests** in `server/file-view.test.ts`, neither using sleeps:
- "keeps a large file's exact length while many answers let go of wait
to be collected (#2286)": it lets go of 1,024 answers, makes the next
one before the event loop turns, and fetches it over HTTP. It fails 3 of
3 on main (`content-length` null) and passes here.
- "holds no more such bodies than a quarter of this process's open files
(#2286)": with the limit set to 1,024, the answer after 256 let-go
answers is streamed, whole. It fails 3 of 3 on the round-2 version
(6eda965), which ignored the limit, and passes here.
- "answers a burst of ranges while many bodies are held without stopping
the event loop for a collection (#2286)": the seek-burst bound. It wraps
`Bun.gc` and asserts that no forced collection runs while 1,024 ranges
are held. It fails 3 of 3 on the first version and passes here.
- The bound is not a wall-clock event-loop limit, which would flake on
loaded runners, as this repo's timing ratios have (#2084, #1901).
- **A host whose hard limit is 1,024** (Codex's reproduction: `ulimit
-Sn 1024; ulimit -Hn 1024`, 256 reserved descriptors, 10,000 range
reads, a 1M-object heap): all 10,000 answered 206 with the right bytes,
peaking at 542 descriptors, the same as main's 542. The round-2 version
returned 7,968 404s with `EMFILE`. Each collection request cost 1.5–5.9
ms on the thread.
- `bun test server/file-view.test.ts server/file-pool.test.ts
server/file-routes.test.ts server/claude-store.test.ts`: 197 pass, 0
fail. `bun run typecheck` is clean.
- No `REMOTE_BUNDLE_VERSION` change: only a release PR raises it.

## Reviews

The round-1 reviews (omo, Codex Sol 6.1 Fast xhigh) and the merge pass's
MEDIUM are in the PR comments. The round-2 reviews of this design are in
a comment below.

## Known limits (LOW, not fixed here)

- **Slow disks and other platforms still stream without a length.** On a
slow disk, a scratch file larger than one read is still streamed without
a Content-Length, and so is every such file on macOS and Windows, as
before (#2265).
- **Past the cap, answers stream without a length again.** Under
sustained load with no full collection the held count keeps growing
(about 270 a second at 64-way in omo's 96 s run, 25,626 held after
150,000 downloads), so the 32,768 cap is reached after roughly 200,000
downloads at that rate, about 800 MB/s for minutes. The answers past it
still arrive whole.
- **A larger cap keeps deleted scratch files' disk space a while
longer.** Up to 32,768 descriptors, against 256 before, can keep a
deleted file's space in use until a full collection. On a host whose
hard limit is 1,024, the cap stays 256, so heavy parallel load there
loses lengths as on main.
- **Held descriptors wait for a collection.** Up to a quarter of the
open-file limit (at most 32,768) can stay open until a collection runs,
where up to 256 could before.